WARNING: This program is designed to scramble hard disks! Read the documentation before using it!
Contents
Part I
• Introduction
• Purpose
• How it Works
• Restrictions
• Future Directions
• Using Assimilator
• What Comes in the Package
• Creating a Customised Assimilator
• Creating a Source Folder
• Assimilator User and Source Folder Permissions
• Ready To Run
• Check List
• Further Configuration
• Abort Password
• Minimum Free Space and Trash Management
• Minimum Rerun Time
• Registering
• Site Licensing
•Getting More Help
• The MacLabManager Mailing list
• Fine Print
• Acknowledgements
Part II
• The Database of Deviancy
• Database Concepts
• The Key to Identify By
• Database Operations
• Adding Entries Quickly
• The Import/Export Business
• Fine Tuning
• Assimilator Log
• Labelling Your Source Folder
• Action Reference
• Customising Label Actions
• Miscellanea
• Desktop Database
• The Desktop Folder
• Blessed are the System Folders
• Special Files and Folders
• Aliases Explained
• Destination Disk Choice
• Time is Relative
• Backdoor Reference
• Assimilator Boot Floppy
• Even More Miscellanea
• Conclusion/Confusion
Introduction
Purpose
Assimilator is designed for situations where you wish to make a large number of Macintoshes look virtually identical. Typically this is in an educational laboratory situation — this document is aimed at laboratory administrators — but Assimilator has other uses, such as setting up newly purchased Macs, testing software or setting up demo machines.
This document is rather long but it pays to read the entire thing through at least once. It is full of helpful hints and tips about setting up Assimilator and your Macintosh laboratory.
How it Works
When Assimilator runs on a laboratory Macintosh it will mount an AppleShare file server and then make the hard disk look virtually identical to a pre-specified source folder on the server. It does this by comparing each file in the source folder to the corresponding file on the destination hard disk. If the file on the destination is missing, or has been changed, then it is thrown away (into the Trash) and a new copy of the file is copied down from the source. Any extraneous items on the destination are also thrown away. Finally aliases, icon positions, folder views, Finder flags and so forth are all set to match those in the source folder. This entire process is known as assimilation.
Restrictions
Assimilator makes no attempt to secure its files from malicious users. If you have malicious users, then you will need to take additional steps to protect your system, including installing additional software like LabMaster and making your System Folder invisible and so forth.
Assimilator requires System 7 and a hard disk.
Future Directions
Possible future directions might include synchronizing folders on different machines or maintaining staff System Folder and/or Application folders, but for now Assimilator is not suitable for such purposes.
Using Assimilator
What Comes in the Package
The following files are including in the Assimilator distribution:
README!
A warning about the dangers of running Assimilator without reading the documentation.
Assimilator Admin
The main program that controls Assimilator.
Documentation
This document.
Register
A program that you should use when you decide to register Assimilator.
0Programs
A list of my other public domain, freeware, shareware and commercial products.
You’ll notice that there is no “Assimilator” program contained in the distribution. This is because you use the Assimilator Admin program to generate Assimilators that are customised for your environment.
Creating a Customised Assimilator
When you run Assimilator Admin it creates a new, untitled customised Assimilator and displays it in a window. The window contain five areas:
Source
This panel lets you specify the source folder for the Assimilator. You must fill out this before you can create an Assimilator that performs any useful action. Creating a suitable source folder is discussed in the next section.
Kind
The controls in this panel specify what type of file this Assimilator will be saved as. Understanding this is critical to understanding how Assimilator works and it is discussed later in this section.
Miscellaneous
This area lets you set various sundry preferences. It is fully described in a later section.
Label Actions
This area lets you associate specific action with specific Finder labels. These actions are described fully in a later section but normally the default actions are OK.
Edit Database
Each Assimilator also holds a database that it consults when it wants to set machine specific parameters. The database is discussed in a later section.
The key to understanding Assimilator is the Kind panel. Assimilator Admin works on documents — that is, customised Assimilators — which are themselves either documents, applications or extensions. When you save a customised Assimilator from within Assimilator Admin it creates the appropriate kind of file, depending on the settings in the Kind panel.
If you save your customised Assimilator as an application then it will start Assimilating whenever it’s launched. You can put it in the Startup Items folder (to run at system startup), the Shutdown Items folder (to run at system shutdown) or in a convenient place, so that users can run it manually. If you run Assimilator as a Shutdown Item you also need to put the Assimilator Helper extension in the Extensions folder (the extension tells Assimilator if the machine is being shutdown or restarted).
One problem with putting Assimilator in the Startup or Shutdown Items folders is that it won’t run if it is invisible. [The Finder refuses to launch any invisible items.] To get around this you can save Assimilator as a system extension. Assimilator loads a small nub at startup time (like any other system extension) and waits for startup time to finish. It then automatically launches itself, which then assimilates the system.
Note: Assimilator cannot run at Shutdown time if it is a system extension.
Finally you can save the Assimilator as a document, which contains just the configuration information. This is a useful way of storing and transporting a configuration without any danger of it accidentally being executed. Also, at some points Assimilator Admin will only let you save a configuration as a document because the configuration does not contain enough information to be a valid Assimilator.
Creating a Source Folder
Once you have created your new untitled Assimilator, you need to start filling out some of the fields. The first step is to create a source folder. This is a folder on a file server that acts as the master folder for all the assimilated clients.
The best way to create a source folder is to set up a single client machine just the way you like it and then copy that machine’s entire hard disk up to the file server. While there are some caveats with this method, it is a good way to start.
When you copy up the hard disk to the file server you will notice that all of the aliases on the server still point back to the hard disk. This is obviously incorrect. You need to fix those aliases so that they point to the appropriate item inside the source folder. That way, when Assimilator copies the alias down to the destination disks, it will fix the aliases.
Assimilator User and Source Folder Permissions
When Assimilator runs on the client machines, it needs to mount the server that contains the source folder. To do this it needs an username (and password) that has sufficient privileges to see the source folder. It is strongly recommended that you give Assimilator its own dedicated username (normally “Assimilator” but you can give it any name you like), and that this user be highly restricted. Specifically the Assimilator user should not have any permissions to write to any volumes on the file server. Also the user’s password should not be the same as any of your administration passwords.
Note: The Assimilator user’s password is inherently insecure because it is stored inside the Assimilator on each of the lab machines. Although the password is scrambled, to prevent idle snooping, it is not effectively encrypted.
You should now set the permissions on the source folder so that the Assimilator user can see all of the enclosed files and folders. The best way to do this is to make yourself (the administrator) owner of the folder — with See Folders, See Files and Make Changes privileges — and make the Assimilator user the group of the folder — with only See Folders and See Files privileges. Don’t forget to make all of the enclosing folders the same as this, otherwise you’ll end up with a half-assimilated machine!
Now that you’ve created the source folder and the Assimilator account you should fill out the items in the Source panel of the customised Assimilator’s window. In preparation for doing this, mount the file server using the Assimilator user’s account and password and check that the user can see all of the items within the source folder. Then click button in the source panel and use the standard directory dialog to set the source folder. Then you should fill in the Username and Password fields with the Assimilator user’s name and password.
Note: If you leave the username field blank then Assimilator will attempt to log in to the file server as a guest.
Ready To Run
At this stage you can save your customised Assimilator as either an application or an extension and use it in action. In fact, it might be a good idea to try it out. Just take a copy of the Assimilator to a lab Mac and run it. It should automatically mount the file server, synchronise the Mac’s hard disk with the source folder and then restart the machine. If not you should consult the check list at the end of this section.
Note: Assimilator virtually always restarts the machine at the end of an assimilation. This is because it has almost always downloaded new versions of some files and the Mac must restart in order for these to take effect.
WARNING: If you save this customised Assimilator as an application then running it is extremely dangerous, because it will automatically start Assimilating the local hard disk. Do not double click it to edit it, because that will run it! Instead, use Open from Assimilator Admin’s File menu to open the Assimilator.
After you have tested your newly created Assimilator, you might want to customise it further. To do this, use the Open command on Assimilator Admin’s File menu to open the Assimilator. There are a number of extra configuration options you might want to explore. These are discussed in the next section.
Check List
These are the steps required to create a minimal customised Assimilator. If you have troubles getting it working then make sure that you have performed each of these steps.
1. Create a source folder by dragging a copy of the lab machine’s hard disk on to the file server.
2. Create an Assimilator user on your file server.
3. Set the privileges of the source folder so that the Assimilator user can see all of the folders and files within the source folder.
4. Mount the server volume containing the source folder using the Assimilator username and password.
5. Check that you (that is, the Assimilator user) can see the source folder.
6. Run Assimilator Admin and create a new untitled Assimilator.
7. Set the source folder by clicking on the button in the source panel.
8. Set the Assimilator username and password using the items in the source panel.
9. Set the Kind to Application.
10. Save the Assimilator.
Further Configuration
Once you have got a working Assimilator you can continue to configure it. There are a number of configuration options you might want to explore in order to gain better security and efficiency.
Abort Password
When Assimilator is assimilating a client machine, it displays a dialog with a Stop button. It’s obvious that a student in the laboratory should not be allowed to stop the assimilation, so the operation is password protected. You can set the abort password in the Miscellaneous panel of the Assimilator’s configuration window.
When Assimilator is running and a user clicks the Stop button, they are presented with a dialog asking for the abort password. If they enter the correct password then Assimilator stops. If they enter the incorrect password then the assimilation continues. Finally the password dialog times out after 30 seconds, so the assimilation continues if no password is entered.
Minimum Free Space and Trash Management
The Miscellaneous panel also holds an item where you can set the minimum free space that Assimilator should guarantee. At the end of the assimilation, Assimilator will delete items in the Trash to ensure that this amount of space is free on the destination disk. Normally you would set the minimum disk free space such that there is enough space for standard user operations, such as editing a large word processor document. Assimilator defaults to a setting of 2MB.
Leaving the minimum free space low is good because, if a user accidentally saves a file on the local hard disk of a machine, it will stay around in the Trash for a while. On the other hand, if you are a particularly fascist system administrator, you can set the minimum disk free space to a very large number, thereby ensuring that any files thrown away by Assimilator are automatically deleted.
The exact trash management scheme it uses is described in the following paragraphs.
Under normal circumstances, Assimilator puts any files it wishes to discard into the Trash. Obviously this process cannot continue indefinitely; sooner or later the disk will fill up. So Assimilator is forced to make decisions about which files to delete. It does this by deleting the oldest files first. To do this it uses a sophisticated Trash management scheme.
When it commences an assimilation, Assimilator creates a folder in the trash called “Assim ddmmyy hhmm”. It then puts any file that it needs to throw away into that Assimilator trash folder. This means that all the files in the Trash are recorded by the time and date when they were assimilated.
When Assimilator discovers that the disk is too full it starts deleting files in the Trash. It progressively deletes the files in the oldest Assimilator trash folder in the Trash until there is enough space free. If deleting all of the Assimilator trash folders fails to yield enough disk free space then it starts deleting files at the top level of the Trash; these are normally the files that users have discarded.
Minimum Rerun Time
Just like a television station, Assimilator has a minimum time before it will run the same program again (–: You can set this time minimum rerun time, in minutes, in the Miscellaneous panel of the Assimilator’s configuration window. The default is 10 minutes.
This rerun time has a number of consequences. If you have Assimilator set to run at startup, either by putting an Assimilator application in the Startup Items folder or by putting an Assimilator extension in the System folder, then you must be careful to set the minimum rerun time to longer than the time taken for the machine to assimilator and then restart. If the time expires before Assimilator has had time to run, assimilate and restart the machine, then it will notice that the time has expire and automatically run again, looping forever, or until an exasperated system administrator fixes it.
At times it may be useful to set the minimum rerun time to 0 minutes. One common technique for setting up a lab is an Assimilator extension that runs at startup time to clean up the machine when it restarts and to have an Assimilator application (with an obvious name like “Clean Hard Disk”) on the desktop. This way, if a user encounters a machine that is broken they can fix it by running the “Clean Hard Disk” application, somewhat more obvious than restarting. You could also imagine a situation where you don’t even have a copy of Assimilator in the Extensions folder and all hard disk cleaning is done under user control.
If you hold down the control key while launching Assimilator, it will run regardless of the minimum rerun time. This is particularly useful for testing changes to your source folder.
Note: The time of the most recent assimilation is stored in the Backup date of the Assimilator application or extension. If you use a backup program that sets this date, Assimilator may run more than required. Also, if Assimilator downloads a new copy of itself (typically because you modified the version in the source folder), then the new version will not have been run and it’s backup date will be unset. This means it will always assimilate, even if it’s just to set its own assimilator time. Under certain circumstances it is possible for Assimilator to run three times before things settle down.
Registering
This program is Shareware, which means if you use it, you must pay for it. A single machine license costs US$10. The upgrade is free if you purchased your copy of Assimilator after January 1, 1996. Otherwise the upgrade is 50% of the normal price.
Note: Assimilator is licensed on the basis of the number of (lab) machines Assimilator is running on, not on the number of copies of Assimilator Admin used. A single user license means you may run a single copy of Assimilator on a single machine. If you wish to run more than 50 copies of Assimilator you should consider purchasing a Site License. (See the next section.)
You can pay in one of two ways: on-line registration using a web browser, or off-line registration using the Register program.
Our online registration can be found at:
<http://order.kagi.com/cgi-bin/register1.cgi?PL>
Or, using the Register program, you need to:
1. Get hold of a copy of the Register program: Register is distributed with the Assimilator package. You can also get Register from the following sites:
<ftp://ftp.stairways.com/>
<ftp://mirrors.aol.com/pub/peterlewis/>
<ftp://ftp.amug.org/pub/peterlewis/>
..or there are download links on the following Web page:
<http://www.stairways.com/register/topay.html>
2. Run the Register program and fill out the form: You need to enter your name, email, postal address, and the shareware you wish to pay for. The form accepts many different payment methods such as: US Check, Money Order, Cash (in many different currencies), Visa, Mastercard, American Express, First Virtual, and Invoice (to be given to your accounts payable department).
3. Send it to Kagi Shareware: Then either email the data generated by the registration program or print it and send it via postal mail or fax. Credit card information is encoded by the Register program.
The address to send the completed form is output by Register when you Print or Copy the completed form. The addresses are:
Email: shareware@kagi.com
FAX: +1 510 652 6589
Snail-mail:
Kagi Shareware
1442-A Walnut Street #392-PL
Berkeley, California, 94709-1405
USA
You may distribute this program any way you wish as long as you don’t charge for it (reasonable download costs such as Compu$erve are ok (although who would call Compu$erve’s download costs reasonable?)). You must distribute the package in its entirety. We don’t guarantee any support, but we always answer my Email. If we don’t answer Email it is because your message didn’t get to us, or our reply bounced, so please try again and include a valid Internet address if you can.
You MAY NOT DISTRIBUTE this program on any disk or CD without our explicit permission.
Australians may pay in Australian dollars direct to us if they prefer.
Site Licensing
World-wide license: US$2000
Universities or companies site license: US$500
Curtin University and the University of Western Australia are exempt.
A site license covers usage of Assimilator on an unlimited number of machines within 100 miles of some arbitrary central point which are owned by the licensed organization. (A site license will not be useful unless you intend to run more than 50 copies of Assimilator.)
World Wide licenses remove the 100 mile radius restriction.
Getting More Help
Up to date information on Assimilator is maintained on the Assimilator home page:
<http://www.stairways.com/assimilator/>
This includes Frequently Asked Questions, Documentation, Registration information, download links for the latest version of Assimilator and additional notes and links relating to Lab Management. If the web site does not help you can mail the Stairways Support address at:
<support@stairways.com.au>
We answer all our e-mail. If you do not get a response, please try mailing us again since your mail may not have got to us.
The MacLabManager Mailing list
If you use Assimilator there is a good chance you will be interested in the MacLabManager mailing list: “A mailing list for the discussion of maintaining laboratories of Macintosh computers.” (We started this mailing list, in part, for discussion of matters Assimilator.) You can find out more about the list and how to subscribe at:
There is also sister documentation to the Assimilator Documentation which tries to fit Assimilator into the bigger picture of Lab Maintenance, called ‘A Lab Management Overview’ available at:
Peter Lewis and Stairways Software Pty Ltd hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Peter Lewis and Stairways Software Pty Ltd will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if Peter Lewis, Stairways Software Pty Ltd, or an agent of his has been advised of the possibility of such damages. In no event shall Peter Lewis or Stairways Software Pty Ltd be liable for any damages, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software.
US Government:
Government End Users: If you are acquiring the Software and fonts
on behalf of any unit or agency of the United States Government, the
following provisions apply. The Government agrees:
(i) if the Software and fonts are supplied to the Department of
Defense (DoD), the Software and fonts are classified as "Commercial
Computer Software" and the Government is acquiring only "restricted rights"
in the Software, its documentation and fonts as that term is defined in
Clause 252.227-7013(c)(1) of the DFARS; and
(ii) if the Software and fonts are supplied to any unit or agency
of the United States Government other than DoD, the Government's rights in
the Software, its documentation and fonts will be as defined in Clause
52.227-19(c)(2) of the FAR or, in the case of NASA, in Clause
18-52.227-86(d) of the NASA Supplement to the FAR.
Acknowledgements
This program was designed by Quinn & Craig Richmond to solve lab problems that they had (mainly fighting with RevRDist). Jon Nielsen & Craig designed the icons. Quinn designed the Assimilator window and wrote this (much improved) documentation. Mike Schon-Hegrad, Peter Cooper and the others provided valuable early beta testing and suggestions. All I did was write the code :-)
